Magnum One/Magnum One (Mid-American Digital) (Disc Manufacturing).iso/d18/tpa2_a.arc/TP&ASM.DOC

Text File | 1991-04-28 | 21KB | 531 lines

  TP&Asm           Integrated Compile-Time Assembler          Version 2 ß
  TP&Asm-M   Memory Mode Assembly Language Development Tool   Version 2 ß

                Copyright (c) 1989  Richard W. Prescott
                          All Rights Reserved

═══════ Built-In Assembly Language Support for Turbo Pascal Compilers ═══════

 All brand and product names mentioned herein are trademarks or registered
                trademarks of their respective holders.

  ┌─────────────────────────────────────────────────────────────────────┐
  │  This file contains information of a general nature, including      │
  │  getting started quickly, and purchasing TP&Asm.  For detailed      │
  │  reference information to enable you to make most effective use of  │
  │  the TP&Asm assembly environment, please see the archive TPA2-R     │
  │  (available 2/21/89).                                               │
  └─────────────────────────────────────────────────────────────────────┘


The following topics are described below:

1. Overview
2. Features
3. System Requirements
4. Getting Started
5. Comparison of Methods
6. Quality Control
7. DISCLAIMER
8. TP&Asm vs TP&Asm-M
9. Purchase Information



Note:

TP&Asm-M refers to the sharable program file TPAM.EXE included in
this archive.  TP&Asm refers to the program file TPA.EXE which is
not included in this archive but which may be purchased, if desired,
as described in section 9.  All references in sections 1 through 5
apply to both TP&Asm and TP&Asm-M.  See section 8 for further
details.



1. Overview

TP&Asm and TP&Asm-M are integrated assemblers for Turbo Pascal
versions 4.0 and 5.0 which operate during the compile step to
provide support for the four TP&Asm keywords "Assemble" (or
"Assembly"), "Internal", "CsData", and "Asm":

      Assemble                       Internal <DataName>
        ∙                              ∙
        (Assembly                      (Assembly
         Instructions)                  Instructions)
        ∙                              ∙
      End;                           End;

      CsData
        ∙
        (Db, Dw, or Dd
         Statements)
        ∙
      End;

      Asm <Assembly Statement>;


Briefly:

  "Assemble" defines a block of standard 8086 assembly language
    statements which can be placed wherever an Inline statement
    would be valid (including 'Inline Directives').

  "Internal" provides support for assembly language code originally
    designed for an external assembler.

  "CsData" defines a block of initialized or uninitialized data
    which is allocated in the current Code segment and is
    accessable throughout the current Unit (used primarily with
    customized interrupt procedures and resident applications).

  "Asm" provides a concise way of specifying single-line assembly
    sections.


As of Version 2, the following compilers are supported:

      TURBO.EXE    Version 4.0 and Version 5.0
      TPC.EXE      Version 4.0 and Version 5.0


Example:

The following simple function compiles successfully when a
supported compiler is run under TP&Asm:

      FUNCTION DosMajorVersion: BYTE;
      BEGIN
        Assembly
          Mov Ah,30h ;or use $30 or 030 to indicate hex
          Int 21h
          Mov DosMajorVersion,Al ;put in function result
        END; {Assembly}
      END; {FUNCTION DosMajorVersion}
       ∙
       ∙
      IF DosMajorVersion >= 3
      THEN { get program name from "environment" ... }



2. Features of TP&Asm/TP&Asm-M

 ■ Runs Turbo/TPC as a subprocess.  Simple to use, yet powerful
   enough to run ANY command line under TP&Asm.  For example,
   "tpam Command" can be used to make TP&Asm-M "Memory resident".
   See the archive TPA2-R (available 2/21/89).

 ■ Compact: Program size 43K, TOTAL Memory usage less than 55K
   (Frees its own "environment" block for reuse by the subprocess)

   - yet -

 ■ Imposes NO limits on Source Code size, Object Code size, or Data
   Seg symbols.  (Your program must still satisfy any Compiler
   limits, however)

 ■ Fast Assembly from Memory - TP&Asm imposes NO additional disk
   access time, even for Include files.

 ■ Fully compatible with the Turbo 5.0 integrated debugger.  The
   Unit ASMWATCH (included) allows you to Watch, Evaluate, and
   Modify the state of all CPU registers and flags.

 ■ Fully integrated with the Turbo built-in Linker.  Permits direct
   Call, Jmp, and Offset references to Pascal Proc/Functions.
   (These references are recognized by the Turbo Smart Linker).

   - yet -

 ■ Units compiled with TP&Asm may be Used in Pascal programs compiled
   without TP&Asm.

 ■ Freely mix Pascal and assembly sections.  Pascal Labels placed
   in assembly sections can be the target of any GOTO statement.
   Assembly statements can branch to (Jmp, Loop, jNZ, etc) or Call
   any Pascal or assembly label.

 ■ Performs automatic Jump-Sizing for all backward AND FORWARD
   Jumps and Loops.  Always builds smallest possible instruction
   (does not pad code with NOPs).

 ■ Supports all 8086 Assembly mnemonics and all assembler directives
   that make sense within a Turbo Pascal program.

 ■ Supports numerous extensions for compatibility with Eric
   Isaacson's A86 Assembler (Multiple operands to Push, IF's, Local
   Labels, etc).

 ■ Recognizes all common decimal and hexidecimal numeric formats,
   including leading '$' for compatibility with Dave Baldwin's
   INLINE.COM.

 ■ Automatically supplies correct segment override and base register
   needed to reference most Pascal and Assembly variables.  (This
   feature may be disabled for "WYSIWYG" assembly).

 ■ Allows setting function results by name, e.g.:
   "Mov FunctionName,TRUE" (Automatically recognizes Built-In
   compiler symbols such as TRUE).

 ■ Provides extensive syntax error checking, completely integrated
   with the compiler's syntax checking.  The cursor is placed at the
   point in your assembly language code where the error occurred.

 ■ Supports Warning level errors, with option to Ignore or Halt on
   warnings.

 ■ Does not disable "Inline" or "External" - these keywords are
   still available, but are no longer necessary.  Any or all of
   the keywords Assemble, Internal, External, and Inline may be
   used in each program or unit.



3. System Requirements

TP&Asm and TP&Asm-M Version 2 ß require: the IBM PC version of Turbo
Pascal 4.0 or 5.0 running on an IBM PC or Compatible, with Version
2.0 or above of MS-DOS or PC-DOS.  Minimum memory requirements are
55K more than the memory required by the compiler.



4. Getting Started

This archive contains the full working version of the TP&Asm-M
Memory Mode Assembly Language Development Tool.  If you have a
supported compiler, simply type 'tpam' in place of 'turbo' at the
system prompt.  TPAM will automatically find and run turbo.exe,
using the same search sequence as DOS.  (See the archive TPA2-R,
available 2/21/89, for other command line options when starting
TP&Asm).

Now read in some of the test files.  Browse through them to see
what they do, then compile and run them.  Modify them and run again.
Turbo Version 5 users, set up the watch expressions as indicated in
the file DEMONEW.PAS and observe the CPU registers and flags as you
single-step through the assembly code.  Observe how easy it is to
experiment with assembly language in your programs.  Observe the
response to syntax errors.  TP&Asm does not intrude into your
programming environment - you are running Turbo Pascal, and the
assembler is integrated so smoothly into the system that you may
forget you are using it.  It is active, however, every time the
compiler calls upon it to translate an Assemble or Internal
statement.



5. A Comparison of (Assembly Language) Methods

This section discusses advantages and disadvantages of the four
basic methods of using machine code/assembly language within a Turbo
Pascal program:  Inline and External (as provided by Turbo Pascal),
and Internal and Assemble (provided by TP&Asm).  (Skip this section
if you're already convinced).

INLINE:

The disadvantage of the Inline statement is obvious - no support for
mnemonics.  Every instruction must be assembled by hand, jumps and
loops are essentially impossible, etc.  Direct calls to Pascal
Procedures and Functions are not permitted.

An advantage, however, is that code may be placed anywhere in the
code stream, not just into separate callable Proc/Functions, and
Turbo identifiers may be referenced by name.  In addition, Inline
statements may be used to define machine code MACROs.

EXTERNAL:

The advantage of External is, just as obviously, full support of
assembly mnemonics (or whatever subset is supported by your external
assembler).  May also permit access to the symbol "SEG DATA" for
restoring the program Data Segment (useful in interrupt routines).

Disadvantages of External are:

  Code must always go into separate callable Global Proc/Functions.

  Limited support for Global Pascal identifier references.
   Referenced identifiers must be declared in EXTRN statements.

  Limited "dead code removal" - Turbo Pascal links in External .OBJ
   modules in an "all or nothing" fashion.

  All references to Proc/Function parameters and Function results
   returned on the stack must be coded explicitly (not referenced
   by name) and may need to be changed for future versions of the
   compiler.  Note however that Borland's TASM provides the
   ".MODEL TPASCAL" directive which permits the same simplified
   parameter references as the TP&Asm Assemble statement.


INTERNAL:

Internal is essentially a direct replacement for External,
supporting 8086 Assembly mnemonics and access to the symbol
"SEG DATA".

Improvements:

  Full support for Global Pascal variable references with no need
   for EXTRN.

  Full "dead code removal" on a Proc by Proc basis within each
   INTERNAL statement.  Permits development of efficient libraries
   of assembly routines compiled into standard 4.0 or 5.0 TPUs.

Not Improved:

  Code still must go into separate callable Global procs.

  Parameter and function results must still be explicitly coded.


ASSEMBLE:

Advantages:

  As with External, supports 8086 Assembly mnemonics and access to
   the symbol "SEG DATA" (8087 mnemonics are not yet supported).

  As with Inline, code may be placed anywhere in the code stream,
   INCLUDING in the definition of (assembly) Inline Directive/MACROs

  As with Internal, provides full support for global Pascal variable
   references without EXTRN, and permits direct Call (or Jmp) to any
   Pascal or Internal Proc/Function.

  In fact, all Pascal variables/parameters which are global or local
   to the current Proc/Function may be referenced by the standard
   Pascal name (without '[BP]', 'CS', etc.).  Function results may
   likewise be put in by name.  There is no need to be concerned
   with the details of Stack usage and parameter passing for any
   particular compiler.

  Provides capability of allocating and referencing NAMED
   initialized (or uninitialized) data in the current code seg.


To summarize,

 In terms of coding convenience:
    ■ External is a major improvement over Inline
    ■ Internal is a moderate improvement over External
    ■ Assemble is a major improvement over Internal and External

 In terms of flexibility of use:
    ■ Assemble and Inline have advantages over External and Internal


It should be clear at this point that the Assemble statment provides
the most versatile and convenient means of including assembly
language in your programs.  Now consider the fact that with Assemble
(and Internal) you don't need to leave the compiler at any point
during your program development, and you can see that TP&Asm offers
you an immense improvement in program development speed.  The time
consuming assembly development loop of:
Exit Turbo/ Assemble/ Reenter Turbo/ Compile &/or Link/ Test/ Repeat
is replaced by the simple and familiar  Edit/Run/Repeat  loop.
With TP&Asm you can be wrapped up & on your way home while others
are still watching their assemblers clean up temporary disk files.


Even if your primary goal is to write stand-alone assembly programs,
consider the advantage of using Turbo/TP&Asm as a program
development environment.  You can develop, test and debug your
assembly routines using all the power and flexibility of Pascal in
the testing process - then port your code unchanged** to A86 or
your favorite stand-alone assembler.  See, for example, HEXBYTE.PAS.

** regarding compatability:  essentially, it is a simple matter to
   design your code so that it requires NO changes in porting from
   TP&Asm to A86, MASM, TASM, or any assembler that is reasonably
   compatible with one of these.  You must of course avoid using
   any TP&Asm enhancements that are not supported by your assembler.


The paragraphs above address the issue of why you should use
TP&Asm when you use assembly language ... but why use assembly
language at all?

The two principal reasons for using assembly language in a Pascal
program are:
   1) To do something that cannot be done in Pascal
      (MICROMTR.PAS; also see the archive TP-TSR)
   2) To do something much faster than it can be done in Pascal
      (FIND.PAS, COMPARE.PAS)
A third reason, to minimize code size, has become less important
with the advent of cheap memory chips and hard disks.  One would
seldom want to go to the trouble of recoding a major application
in assembly language simply to save code size.  (An exception is
the "memory resident" type program, where mimimum code size is
usually very important).



6. Quality Control

This program has been tested by assembling over 6000 variations of
assembly language statements and running the Turbo/TP&Asm output
Exe file through EXAMINE.EXE to produce a "side by side" display
of each assembly source statement together with its corresponding
DEBUG.COM disassembly.  All modifications are retested against the
same test files.  EXAMINE.EXE is provided free of charge on the
TP&Asm distribution disk so that users may easily verify proper
assembly within their own programs.  It can also be found in the
archive TP-XMN, available 2/28/89.  (EXAMINE requires a compiled
EXE and MAP file and a copy of DEBUG.COM).


TP&Asm, TP&Asm-M, and Examine are all compiled and assembled using
TP&Asm Version 2 ß running Turbo Pascal Version 5.0.



7. DISCLAIMER OF WARRANTY

This software and accompanying documentation are sold "as is" and
without warranties as to performance or merchantability.

This program is sold without any express or implied warranties
whatsoever.  Because of the diversity of conditions and hardware
under which this program may be used, no warranty of fitness for a
particular purpose is offered.  The user is advised to test the
program thoroughly before relying on it.  THE USER MUST ASSUME THE
ENTIRE RISK OF USING THE PROGRAM.  ANY LIABILITY OF THE AUTHOR WILL
BE LIMITED EXCLUSIVELY TO PRODUCT REPLACEMENT OR REFUND OF THE
PURCHASE PRICE.



8. TP&Asm vs TP&Asm-M

"TP&Asm" refers to the Integrated Compile-Time Assembler package
containing the program file TPA.EXE.  TPA supports Compile to Disk
as well as Assemble/Compile and Run within the Turbo environment.

"TP&Asm-M" refers to the sharable Memory Mode Assembly Language
Development package which contains the program file TPAM.EXE, but
does not contain TPA.EXE.  TPAM provides the same assembly language
capabilities as TPA, but is intended only for assembly language
development within the Turbo 4.0 or 5.0 integrated environments,
and therefore does not have the capability of compiling to disk.
(You can of course read and save Pascal and Assembly SOURCE files
with both programs).

The TP&Asm-M package is sharable, however the TP&Asm package is not.


Why not distribute both TP&Asm and TP&Asm-M as shareware?

I have given a great deal of thought to this.  I did not wish to
annoy potential users by creating a limited demo version which
provides no useful function.  At the same time, however, I feel
strongly that a shareware user who registers a program would
appreciate receiving some sort of genuine "bonus" beyond a printed
copy of the documentation file.  I have attempted to resolve this
conflict by creating what I believe to be a useful program (TP&Asm-M)
which is fully sharable and which demonstrates ALL the features
of an even more useful program (TP&Asm).  Users may register for
TP&Asm and receive a genuine bonus, or register for TP&Asm-M only,
at a considerable discount.

The usefulness that I attribute to TP&Asm-M is in the opportunity to
dramatically reduce development time for your External and Inline
assembly language routines.  TP&Asm-M permits you to get the heart
of any assembly routine working in a friendly environment that does
not require a series of "assembler overhead" directives and
complicated stack offset parameter references.  Once the routine is
working, you can add in the overhead directives and parameter
offsets, and run the resulting code through your external assembler,
secure in the knowledge than any remaining problems would be due
only to possible incorrect parameter offsets and not to any flaw in
the logic of the assembly routine itself.

TP&Asm-M is also convenient for users who simply want to learn about
and experiment with 8086 assembly language.  With TP&Asm-M and Turbo
Version 5.0 you can single step your experimental code and instantly
view the effects on CPU registers, flags, stack contents, and Pascal
variables in the compiler's Watch window.

Although I firmly believe that TP&Asm-M is a full featured, useful
program, and although it is fully sharable, I have chosen to not
refer to it as "shareware".  This is out of consideration for the
definition used by the Association of Shareware Professionals, who
firmly believe that shareware packages should not be limited in any
way, and who might obviously argue that TP&Asm-M, while useful in
its own right, is still a limited version of TP&Asm.




9. Purchase Information.

After you have reviewed the TP&Asm-M package for a reasonable period
of time (say, 30 days), please register it or purchase TP&Asm if you
plan to continue using it.  Even if you choose not to register, I
encourage you to retain a copy of TP&Asm-M and distribute it to
others via BBS or on diskette.  Please include all files in both the
program and reference archives (TPA2-A and TPA2-R).

If you find that this software does not perform as described, please
let me know.  I am proud of this program and I want it to work right
for you.  If you are dissatisfied, I will refund your purchase price.
I only ask that you clearly state the manner in which it failed to
perform as described when you return the distribution disk (and, of
course, that you discontinue using the program).  I will accept your
judgement without argument.  Consider the spirit in which this offer
is made, and please be fair.

The current version 2 ß is the final beta test stage for TP&Asm
Release 2.0.  As indicated below, users who purchase the current
beta test version and thereby assist me in final verification
receive a $10 discount and a free update when Version 2.0 is
released.


Trial and Update Disks ...  $5 + $3 P&H

TP&Asm-M Registration  ... $19 + $3 P&H for registration + disk
                           $19  (total) for registration only

TP&Asm Version 2.0     ... $49 + $3 P&H (not yet available)

TP&Asm Version 2 ß     ... $39 + $3 P&H including free upgrade
                                          to Version 2.0.

(Wisconsin residents, please add 5% sales tax).

All prices listed are for standard 5 1/4 inch floppy disks.  Add
$2 for distribution on 3 1/2 inch disks.


If you originally purchased a Trial Disk you may deduct $5 from the
above prices when registering TP&Asm-M or purchasing TP&Asm.


Please send a check or money order payable to:

                      Richard W. Prescott
                      724 Sauk Ridge Trail
                      Madison, WI  53705

Please include the following information:

  1. Full Version number of the Turbo Pascal compiler you now use.

  2. Your registration number for that compiler.

  3. If you obtained TP&Asm-M from a bulletin board:
     3a. Area code and phone number of that bulletin board
     3b. Full Version number of the TP&Asm-M version you have
     3c. Directory Date of the README file